Hamilton C shell(tm) User Guide and Reference Manual Release 2.1 April, 1993 Hamilton Laboratories, 13 Old Farm Road, Wayland, MA 01778-3117 Phone 508-358-5715 + FAX 508-358-1113 MCI Mail 389-0321 + Internet 3890321@mcimail.com BIX hamilton + CompuServe 70034,2025 + Telex 6503890321 Copyright (c) 1988 - 1993 by Hamilton Laboratories. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise without the prior written permission from Hamilton Laboratories. Printed in the United States of America. AT, PS/2 and OS/2 are registered trademarks of International Business Machines Corporation. Windows NT is a trademark of Microsoft Corporation. UNIX is a registered trademark of UNIX System Laboratories. Hamilton C shell is a trademark of Hamilton Laboratories. Table of Contents Preface .................................. v License Agreement....................... vii Introduction ............................. 1 Installation Guide ....................... 3 Installation on OS/2 3 Installation on Windows NT 15 Common Problems ......................... 18 Product Support ......................... 29 User Guide .............................. 32 The Utilities 38 I/O Redirection and Piping 55 The History Mechanism 66 Variables 70 Wildcarding 79 Editing 88 Quoting 93 Expressions 97 Aliases 106 Programming Constructs 109 Scheduling 131 Order of Evaluation 138 Customizing the Shell 141 Summary 153 Examples ............................... 155 Factor.csh 155 Whereis.csh 156 Samples Directory 157 Compatibility Guide .................... 162 Language Reference ..................... 172 Basic Statements 172 Condition Testing 172 Iteration 175 Procedures 175 Aliases 176 Variable and Expression Manipulation 176 Local Variables 178 Function Keys 179 iii Miscellaneous Statements 181 Statement Relationships 183 I/O Redirection 183 Expression Operators 185 File System Tests 187 Special Devices 188 Wildcarding and Pattern Matching 190 Filename Completion 192 Command Line Editing 193 History Recall 196 Command Completion 196 Quoting 198 Escape Sequences 198 Variable Substitution 200 Substitution Modifiers 201 Pathname Editing 203 Predefined Variables .................... 205 Environmental Variables 205 Process-Wide Variables 210 Per-Thread Variables 212 Variables, Sorted by Name 218 Built-in Procedures ..................... 230 Utilities ............................... 235 Popular Aliases ......................... 242 Help Information ........................ 248 Help for the shell 248 Help for the utilities 250 iv Preface Thank you for purchasing and using Hamilton C shell. Our goal and guarantee is your satisfaction. Hamilton C shell is an advanced command processing language for OS/2 and Windows NT. It's a professionally- oriented language for manipulating files, processes and threads and connections between these objects. As a language, it offers what we think of as the human characteristics of language: a useful vocabulary and grammar, a limitless freedom of expression and the ability to describe and relate events in time. Most important, it projects your influence into the future by allowing you to easily describe you want done even if what you want is quite complex and dependent on future events. Hamilton C shell is a full implementation of the C shell language popular on engineering workstations. It was created specifically for OS/2 protected mode and meticulously ported to Windows NT. Not one of the more than 95,000 lines of code in the current release was created on or ported from anything but OS/2 or NT. This product complies with accepted standards for the language and with the conventions of OS/2 and NT. Users with previous experience with the standard OS/2, NT or DOS command processors or the original Unix C shell should find enough reasonably familiar language constructs and features to make the product immediately productive. Douglas A. Hamilton Wayland, Massachusetts December 9, 1988 (Last revised April 22, 1993) v vi IMPORTANT -- READ CAREFULLY BEFORE OPENING. By opening this sealed package, you indicate your acceptance of the following Hamilton Laboratories License Agreement. Hamilton Laboratories License Agreement This is a legal agreement between you, the end user, and Hamilton Laboratories. By opening this sealed package, you are agreeing to be bound by the terms of this agreement. If you do not agree to the terms of this agreement, promptly return the unopened package and any accompanying items for a full refund. HAMILTON LABORATORIES SOFTWARE LICENSE 1. GRANT OF LICENSE. Hamilton Laboratories grants to you the right to use one copy of the enclosed Hamilton Laboratories software program (the ``SOFTWARE'') on a single terminal connected to a single computer (i.e., with a single CPU). You may not network the SOFTWARE or otherwise use it on more than one computer or computer terminal at the same time. 2. COPYRIGHT. The SOFTWARE is owned by Hamilton Laboratories or its suppliers and is protected by United States copyright laws and international treaty provisions. Therefore, you must treat the SOFTWARE like any other copyrighted material (e.g., a book or musical recording) except that you may either (a) make a reasonable number of copies of the SOFTWARE solely for backup purposes or (b) transfer the SOFTWARE to a single hard disk provided the original and any other copies are kept solely for backup or archival purposes. You may not copy the written materials accompanying the software. 3. OTHER RESTRICTIONS. You may not rent or lease the SOFTWARE, but you may transfer the SOFTWARE and accompanying written materials on a permanent basis provided you retain no copies and the recipient agrees to the terms of this Agreement. You may not reverse engineer, decompile or disassemble the SOFTWARE. If SOFTWARE is an update, any transfer must include the update and all prior versions. 4. DUAL MEDIA SOFTWARE. If this SOFTWARE package contains both 3 1/2'' and 5 1/4'' disks, you may use only the disks appropriate for your single-user computer. You may not use the other disks on another computer or loan, rent, lease, or transfer them to another user except as part of the permanent transfer (as provided above) of all SOFTWARE and written materials. LIMITED WARRANTY LIMITED WARRANTY. Hamilton Laboratories warrants that the SOFTWARE will perform substantially in accordance with the accompanying written materials for a period of 90 days from the date of purchase. Some states do not allow limitations on the duration of an implied warranty, so the above may not apply to you. CUSTOMER REMEDIES. Hamilton Laboratories' entire liability and your exclusive remedy shall be, at Hamilton Laboratories' option, either (a) return of the price paid or (b) repair or replacement of the SOFTWARE that does not meet this Limited Warranty and which is returned to Hamilton Laboratories with a copy of your receipt. During the first 90 days from the date of purchase, if you determine that the SOFTWARE is unsatisfactory in any way, you may return it with proof of purchase and a written description of why the SOFTWARE was unsatisfactory for a full refund. NO OTHER WARRANTIES. Hamilton Laboratories disclaims all other warranties, either express or implied, including, but not limited to implied warranties of merchantability and fitness for a particular purpose, with respect to the SOFTWARE and accompanying written materials. This limited warranty gives you specific legal rights. You may have others, which vary from state to state. NO LIABILITY FOR CONSEQUENTIAL DAMAGES. In no event shall Hamilton Laboratories or its suppliers be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use this Hamilton Laboratories product, even if Hamilton Laboratories has been advised of the possibility of such damages. Because some states do not allow the exclusion or limitation of liability for consequential or incidental damages, the above limitation may not apply to you. This Agreement is governed by the laws of the State of Massachusetts. Should you have any questions concerning this Agreement, or if you wish to contact Hamilton Laboratories for any reason, please write: Hamilton Laboratories Customer Service, 13 Old Farm Road, Wayland, MA 01778-3117. Introduction Hamilton C shell(tm) Introduction Hamilton C shell is a language for interactively using OS/2 and Windows NT. Compared to the standard OS/2 and NT command processors, it provides a vocabulary and grammar that allows much more complex activities to be described. Some of its major innovations include + Command line editing of enormous statements with arrow keys and filename and command completion. + User-definable function keys. + Fully recursive grammar. Statements can be arbitrarily nested or piped without concern for statement length or other arbitrary restrictions. + Procedures and aliases. The vocabulary of the language is meant to be extensible by the user. + Variables, arrays and expressions. Integer and floating point arithmetic, pattern matching facilities and various file system tests and editing operators provide an expressive grammar. + Threads and processes. Child threads and processes can be spawned to run commands asynchronously or in the background. + Command substitution. The output of one command can be stuffed back on the command line as arguments to another. + History. Past commands can be recalled and edited. + Advanced filename wildcarding. This product complies fully with industry-accepted definitions for the C shell language. The user is not asked to learn yet another new proprietary language not available anywhere else. Instead, a tested, proven framework has been adapted with modern compiler technology for OS/2 and NT: Page 1 Introduction 1. A modern top-down parser is used for better language recognition and performance. 2. It's easier to use. The syntax and grammar has been made flexible and more consistent with other modern high level language conventions. 3. It knows about OS/2 AND NT: HPFS, long filenames, environmental variables, networks, international character sets, how to start PM applications and (under OS/2 2.0) about 32-bit and Virtual DOS machine (VDM) applications. 4. Threads are used extensively to achieve performance and functionality not possible in UNIX. 5. Feedback to the user, especially when reporting errors has been improved. Who is it Designed For? Most users of Hamilton C shell are relatively technically oriented computer users. Often, they're software developers. They have a business need for an OS/2 or an NT system. Peering over their shoulders, they typically have lots of windows open on the screen. Many of the windows are running copies of this shell. Some copies are transient, created to display with little snippets of information needed on the spur of the moment. Other copies of the shell would be used for more long-running projects: for example, getting a make working for a major application. A shell window is like any other application window but with a different paradigm. Instead of data, rows and columns of numbers or lines of text, the object being manipulated is the machine itself. A good shell tackles a different problem than icons and windows. Instead of the point-and-shoot immediacy of ``do this single thing now,'' a shell offers language and the ability to describe more customized or repetitive actions, e.g., identify a suitable set of files, perform some action against them and filter the results in some interesting way. Page 2 Installation Installation Guide This section outlines how to install the Hamilton C shell on your system. If you are installing the OS/2 version, follow the instructions beginning on this page. To install the Windows NT version of Hamilton C shell, please turn to page 15. If you encounter problems, consult the ``Common Problems'' section on page 18 or call us for technical support as described on page 21. Installation on OS/2 The first few steps, copying files from diskette to your hard disk and modifying your config.sys, are the same on all releases of OS/2. The remaining steps -- those associated with actually installing Hamilton C shell on your OS/2 desktop -- depend on which release of OS/2 you're running. We suggest a ``vanilla'' installation initially, but later you may want to customize it to your own tastes. For help with that, read the chapter on ``Customizing the Shell,'' beginnning on page 141. Once you've gained familiarity with both OS/2 and with the C shell, you may want to set up the C shell as the default command processor for OS/2, completely replacing cmd.exe as described on page 10. The advantage to be gained (except under the 6.167 Beta and LA builds of 2.0) is that the C shell will then be able to change its own title bar and icon when you run an external command. System Requirements Installation requires a 286-, 386- or 486-based AT(R) or PS/2(R) or compatible, running OS/2(R) 1.1 (Presentation Manager) or Microsoft SDK 1.06 or later. To run the 32- bit version (expected to be available in January, 1993), you'll need to be running OS/2 2.0 or later. Roughly 1 MB of disk space is used. Hamilton C shell and the utilities supplied with it fully support HPFS and long filenames when running under OS/2 1.2 or later. They will work properly in a Presentation Manager text window or full-screen and with networks such Page 3 Installation as LAN Manager or IBM LAN Server. If you're using OS/2 2.0, it knows how to run 32-bit applications and start up Multiple Virtual Dos machines. The product is not copy protected. Basic Installation, Part I (All releases of OS/2) 1. Copy the executables in the bin directory into any desired directory on your search PATH, so long as it appears ahead of the directory containing the standard IBM/Microsoft more.com. (We supply a dramatically improved more.exe, which should take precedence.) If you're creating a new directory, remember to add it to your search PATH in config.sys and in the login.csh file you create next. 2. Edit config.sys, adding statements to define whatever directory you choose to designate as your HOME directory and to ensure you're configured for a sufficient number of threads. The significance of a home directory is principally that it will be convenient to specify pathnames relative to that directory. The default number of threads is too small if you expect to have lots of windows open. Also, be sure your PATH explicitly lists ``.'', the current directory. You may also want to include definitions for TABS and COLORS. more.exe and some of the other utilities look for TABS to see if you want them to display text with tabs expanded out to something other than the default of every 8 characters. By default, the C shell displays white characters on a black background. The COLORS variable lets you choose something different from this set: black, red, green, yellow, blue, magenta (or blue red), cyan (or blue green) and white. Foreground colors may also be bright, dim, blink or reverse. The keyword ``on'' introduces background colors. (Blink only causes true blinking full-screen; in a text window, it just makes the background brighter. Also, yellow is a true yellow only if it's bright. These are OS/2 limitations not related to the C shell.) For more information on setting screen colors, please refer to the customization chapter or to the colors.csh file in the samples directory. Here's an example of what you might add to config.sys: Page 4 Installation THREADS=255 SET HOME=D:\DOUG SET TABS=3 SET COLORS=WHITE ON BLUE (Please be sure your config.sys file contains only upper-case alphabetics, no lower-case, if you're using OS/2 1.1. Lower-case alphabetics were known to cause random OS/2 system failures in that release of OS/2. This was a known bug in the OS/2 kernel and was not application dependent.) 3. Copy the login.csh and startup.csh files into ``home'' directory. Unless you're convinced that you've set all your environmental variables in your config.sys (and that your PATH explicitly lists ``.'', the current directory), use the dumpenv utility to paste a series of setenv statements into the login.csh file to recreate the environment you've been using with cmd.exe: dumpenv >>login.csh (To see what dumpenv does, look at the source code in the samples directory or simply run dumpenv without redirecting the output.) The login.csh and startup.csh files can be edited with any ascii editor to customize the shell to your needs. The login.csh file has a lot of comments in it which can take the shell a second or more to read; you'll almost certainly want to delete some of them once you've read them so the shell will start up faster. Also, any setenv statements that just duplicate what's in your config.sys can be discarded. The remaining steps depend on which release of OS/2 you're running. Basic Installation, Part II (OS/2 1.1) 4. Add csh.exe with the title ``Hamilton C shell'' to the ``Start Programs'' menu. To do this, pull-down ``Program'' and select ``Add...'' from the menu bar. Fill in: Program title.... Hamilton C shell Path and file name ....as Page 5 Installation appropriate....\csh.exe Parameters.... -L The ``-L'' part tells csh.exe when it starts up that it's a ``login'' shell, which means it should look for a login.csh file. (Refer to page 248 for additional information on other options.) 5. You will likely want to create a second entry for running full-screen. It's more convenient if you're mostly working with applications that only run full- screen or if you want faster text display, especially scrolling. To do that, from the ``Start Programs'' menu, pull-down ``Program'' and select ``Copy...'' from the menu bar. In the Copy Programs popup, fill in the following and push the ``Copy'' button: Change Title to: Hamilton C shell -- Full Screen Back in the ``Start Programs'' window, select the new full screen title, pull-down ``Program'' and select ``Change...''. In the Change Program Information popup, push the ``Change'' button. This brings up the How to Run the Program popup; select ``Run the program full-screen'' and ``Enter''. 6. All the material in the samples directory is provided for its tutorial value; you may or may not wish to copy it onto your hard disk. 7. Reboot your system before starting Hamilton C shell for the first time. This causes the new statements in config.sys to take effect. Page 6 Installation Basic Installation, Part II (OS/2 1.2 or 1.3) 4. Add csh.exe with the title ``Hamilton C shell'' to the ``Group - Main'' menu. To do this, pull-down ``Program'' and select ``New...'' from the menu bar. Fill in: Program title: Hamilton C shell Path and file name: ....as appropriate....\csh.exe Parameters: -L The ``-L'' part tells csh.exe when it starts up that it's a ``login'' shell, which means it should look for a login.csh file. (Refer to page 248 for additional information on other options.) 5. You will likely want to create a second entry for running full-screen. It's more convenient if you're mostly working with applications that only run full- screen or if you want faster text display, especially scrolling. To do that, from the ``Group - Main'' menu, pull-down ``Program'' and select ``Copy...'' from the menu bar. In the Copy Programs popup, fill in the following and push the ``Copy'' button: Change Title to: Hamilton C shell -- Full Screen Back in the ``Group - Main'' window, select the new full screen title, pull-down ``Program'' and select ``Properties...'' . In the Properties popup, push the down arrow next to the ``Program Type:'' box and select ``OS/2 Full Screen'' on the list that will appear and then push the ``Change'' button. 6. All the material in the samples directory is provided for its tutorial value; you may or may not wish to copy it onto your hard disk. 7. Reboot your system before starting Hamilton C shell for the first time. This causes the new statements in config.sys to take effect. Page 7 Installation Basic Installation, Part II (OS/2 2.0) 4. Open the Templates folder and drag a program object to the desktop (or another folder) by pressing and holding the right mouse button as you drag. On the Program page of the ``Program - Settings'' window that will appear, fill in: Path and file name: ....as appropriate....\csh.exe Parameters: -L The ``-L'' part tells csh.exe when it starts up that it's a ``login'' shell, which means it should look for a login.csh file. (Refer to page 248 for additional information on other options.) 5. On the Window page of the Settings, you will probably want to set Minimized button behavior: Minimize window to desktop Object open behavior: Create new window Doing this will let you conveniently open up lots of copies of the C shell as needed. 6. On the General page of the Settings, set Title: Hamilton C shell Close the Settings by pressing Alt-F4. 7. You will likely want to create a second entry for running full-screen. It's more convenient if you're mostly working with applications that only run full- screen or if you want faster text display, especially scrolling. To do that, copy the C shell icon you just created by right-clicking on it and selecting ``Copy...'' and then choosing an appropriate destination folder (probably the desktop) for the copy. You can also copy the icon by pressing and holding the Ctrl key while dragging with the right mouse button. 8. Once you've made the copy, right-click on it and select ``Open'' and then ``Settings''. On the ``Session'' page, select ``OS/2 full screen''. Then go to the ``General'' page and type a new title: Title: Hamilton C shell Full Screen Page 8 Installation Close the Settings window for the copy by pressing Alt-F4. 9. All the material in the samples directory is provided for its tutorial value; you may or may not wish to copy it onto your hard disk. 10. Reboot your system before starting Hamilton C shell for the first time. This causes the new statements in config.sys to take effect. Page 9 Installation Installation as the Default Command Processor The C shell can also be installed as the default command processor OS/2 protected mode, meaning you specify it, not cmd.exe in your config.sys. The principal advantage is that when the when the C shell is run as the default command processor, PM allows the C shell to change its own title bar and, under OS/2 1.3 or 2.0 (but not the 6.167 Beta or LA builds), its own icon to show what it's running. This can be quite helpful if you have lots of copies of the shell running minimized and would like to know what each one is doing. The disadvantage is that the installation is slightly messy and it does disable cmd.exe's ability to change its title bar and icon. For these reasons, most users will want to wait until they've gained some familiarity with the C shell and with OS/2 before installing it this way. To install the C shell as the default command processor, follow the instructions for the basic installation but then make these changes, as appropriate for your system: Default Command Processor Installation Procedure (OS/2 1.2 or 1.3) 1. Edit the PROTSHELL line in your config.sys, replacing the pathname and any parameters for cmd.exe (remembering what they were) with the pathname for the C shell and a -L (login) parameter. The resulting line should look something like this: PROTSHELL=C:\OS2\PMSHELL.EXE C:\OS2\OS2.INI C:\OS2\OS2SYS.INI C:\OS2\BIN\CSH.EXE -L 2. Change the pathname you specify for the C shell in Start Programs or Group-Main to * (an asterisk). Also, change the parameters line to be either blank (1.1 or 1.2) or (1.3): /K "%*" 3. Change the entries (probably named ``OS/2 Window'' or ``OS/2 Full Screen'') in Group-Main or Start Programs for cmd.exe to fill in the complete pathname for cmd.exe instead of an asterisk. Set the parameters to whatever you had specified following the pathname for cmd.exe (if anything) in your config.sys before changing it in step 1. 4. Change any entries in any of your program groups which invoke .cmd scripts to run them via cmd.exe Page 10 Installation explicitly. For example, if you had an entry that specified the program ``c:\myapp\foo.cmd'', change that to: Path and file name: c:\os2\cmd.exe Parameters: /C c:\myapp\foo.cmd ...any additional parameters... 5. Reboot. Page 11 Installation Default Command Processor Installation Procedure (OS/2 2.0) 1. Edit your config.sys to set OS2_SHELL to point to the C shell, specifying the -L (login) option, e.g., set OS2_SHELL=c:\hamilton\bin\csh.exe -L 2. Modify the Settings for the OS/2 Window and OS/2 Full Screen icons to show the full path for cmd.exe (e.g., ``c:\os2\cmd.exe'') rather than an asterisk on the Program page. 3. Modify the Settings for the Hamilton C shell icons to specify an asterisk pathname (meaning the default shell), deleting any mention of any startup parameters and explicitly specifying the C shell icon rather than the default icon: a. Right-click on the icon and open the Settings. b. On the Program page, set Path and file name: * Parameters: c. Select ``Find...'' next to the icon display. d. Select ``Locate'' on the Find screen. e. Select the ``Path'' page on the Locate Folder screen. f. Type the pathname of the directory containing the C shell's csh.ico icon file. (E.g., ``c:\hamilton\bin''.) g. Press the ``OK'' button on the Locate Folder screen. h. Type ``csh.ico'' in the Name field on the Find screen. i. Press the ``Find'' button. j. The Find Results screen should appear with the C shell icon highlighted. Press the ``OK'' button. k. Back in the General Settings screen, you should now see the C shell's icon. Press Alt-F4 to close the screen. Page 12 Installation 4. When you reboot, the C shell will be the default shell and it will appear with its correct icon both for starting and when you minimize it. Page 13 Installation Page 14 Installation Installation on Windows NT This section describes how to install the Windows NT version of Hamilton C shell. System Requirements: Installation requires a 386-, 486- or Pentium-based machine for the Intel x86 version, a MIPS R4000- or R4400-based machine for the MIPS version or a DEC Alpha AXP-based machine for the Alpha version of Hamilton C shell. The machine must be running Windows NT build 404 (March 1993 Beta) or later. Roughly 2 MB of disk space is used on an Intel machine, 2.9MB on a MIPS or 3.5MB on an Alpha. Basic Installation: 1. Copy the contents of the bin and samples directories onto your hard disk, putting them anywhere you like. (Notice that the bin directory is too big to fit on one diskette; you'll have to merge the two or three diskettes, depending on which system you have.) 2. Copy the login.csh and startup.csh files into any directory you care to designate as your ``home'' directory. The significance of a home directory is principally that it will be convenient to specify pathnames relative to this directory. 3. Edit the login.csh and startup.csh files, customizing them to meet your needs. The login.csh file has a lot of comments in it which can take the shell a second or more to read each time it starts up; you'll almost certainly want to delete some of these comments once you've read them so the shell will start up faster. 4. Edit the environment variables by opening the Control Panel and then, within that, opening the system icon. To define a variable through the Control Panel, type the variable name in the ``Variable:'' fill-in box, the value in the ``Value:'' box and click on the ``Set'' button. Page 15 Installation a. Create or edit your entry for the PATH variable, adding the full pathnames for the C shell's bin and samples directories to the list. b. Create an entry for the HOME environment variable, setting its value as the full pathname of the directory where you placed login.csh and startup.csh. c. You may also want to include definitions for TABS and COLORS. The shell and all the utilities look for TABS to see if you want them to display text with tabs expanded out to something other than the default of every 8 characters. By default, the C shell displays white characters on a black background. The COLORS variable lets you choose a combination from this set: black, red, green, yellow, blue, magenta (or blue red), cyan (or blue green) and white. Foreground collows may also be bright, dim, blink or reverse. The keyword ``on'' introduces background colors. (Blink only causes true blinking full-screen; in a text window, it just makes the background brighter. Also, yellow is a true yellow only if it's bright. These are system limitations not related to the C shell.) Other color settings you might want to specify now or at some later time through the Control Panel are MOREPROMPT, MOREFILLIN and MOREERROR (for customizing the more utility's command line) and DELETIONS and ADDITIONS (for customizing the diff utility). For more information on setting screen colors, please refer to the the colors.csh file in the samples directory or to the Customization chapter. Here's an example of the settings you might specify: HOME=d:\doug PATH=d:\hamilton\bin;d:\hamilton;samples COLORS=white on blue TABS=3 ADDITIONS=bright white on green DELETIONS=bright white on red MOREPROMPT=red on white MOREFILLIN=black MOREERROR=bright white on red Page 16 Installation 5. Add csh.exe with the title ``Hamilton C shell'' to the Program Manager. To do this, pull-down ``File'' and select ``New''. A pop-up will appear asking that you confirm this will be a new Program Item. On the next pop-up, fill in: Description: Hamilton C shell Command Line: ....as appropriate....\csh.exe -L The ``-L'' part tells csh.exe when it starts up that it's a ``login'' shell, which means it should look for a login.csh file. 7. Logout of your Windows session and then log back in to cause all the new settings to take effect. Page 17 Common Problems Common Problems When I try to start the C shell in a new window, it dies and goes away before I can read its messages. You've probably made an error on the ``Parameters'' line under OS/2 or in the ``Command Line'' under NT. Under NT, select the icon for Hamilton C shell and press Alt- Enter to examine the properties. Under OS/2, you can force the window will to stay up after the shell exits so you can read the message by following the instructions appropriate for your system: OS/2 1.1: Go to the ``How to Run the Program'' screen by clicking on the C shell entry in ``Start Programs'' and pulling down ``Program'' then selecting ``Change...''. Click on the check box beside ``Close the window...'' and press Enter. OS/2 1.2 or 1.3: Click on the C shell entry in ``Group - Main'', pulling down ``Program'' and selecting ``Properties''. Push the ``Options...'' button and click on the check box next to ``Close window on exit'', removing the X. OS/2 2.0: Right-click on the icon and select ``Open'' followed by ``Settings.'' On the Session page, click on the check box next to ``Close window on exit'', removing the check. The shell doesn't know how to run an external command. One of the environmental variables, particularly HOME, PATH or COMSPEC is probably set incorrectly. Typical symptoms are that the shell doesn't seem to know how to find an external command or that it doesn't know how to run a .cmd file, etc. Another variation might be that it runs the old IBM more.com rather than the new more.exe. If you experience symptoms like these, first check that these variables are set sensibly. The other common possibility under OS/2 1.x is that you're using a network and have execute, but not read access to the application you're trying to run. Due to a bug in the OS/2 1.x kernel, the C shell cannot use the Page 18 Common Problems kernel's DosQAppType function to determine whether the application should be started full-screen, in a text window or as a PM graphics application. Instead, the C shell is forced to read the application's .exe header itself; if it can't read it, it can't run it. The solution is to be sure you have read access. Page 19 Common Problems The shell won't run my new program. Path hashing can sometimes produce surprising results if you create a newer version in your current directory of a command that already exists in another of your path directories. The shell won't know you've done this; its hash will still only list the older version. To overcome this problem, use either the rehash or unhash commands. The shell won't execute commands in the current directory. Your should add the current directory to the list of directories in the PATH variable. cmd.exe always checks the current directory before looking in any of the PATH directories. Hamilton C shell does not make this assumption; if you want the current directory to be first one checked, you should specify it explicitly as ``.'' at the beginning of the list. For example: setenv PATH = '.;c:\os2;c:\os2\bin' The shell keeps running the old version my shell procedure. If you define a shell procedure with proc in a .csh script file and then execute the script, the procedure is compiled into an internal form that's much faster to run and it's kept around in memory to make it run the next time even faster. If you change the text in the script file but don't explicitly throw away the old definition using unproc, the C shell won't know it's supposed to recompile. The shell won't run any cmd.exe internal commands. Most probably, the shell is unable to find your startup.csh file when it starts up. This is the file that should hold the aliases the shell uses to intercept cmd.exe's built-in commands. Check to see that your HOME variable is set to the directory where you've placed startup.csh and that your startup.csh file isn't garbled. When I start an application from the C shell, it dies immediately. Page 20 Common Problems Under OS/2, if you find that an application dies immediately after starting, check that the .exe file is properly marked with its type, i.e., full-screen, PM text windowable or PM graphics. The shell tries to start up an application in accordance with the way it's marked; if it's marked wrong, the application just won't run. Even very recently, a number of PM applications including even e.exe, the System Editor, were being shipped unmarked, which by convention is supposed to mean full-screen. To look at or change how an application is marked, use the markexe.exe utility. (Type ``markexe -h'' for help.) Another possibility is that the application has a bug that makes it fail if the maximum file handle count it inherits from its parent process is greater than 20. This problem has been seen in some past releases of the Microsoft linker (discussed below) and of WordPerfect, for example. You can force the C shell not to bump the file limit when it starts up using the -Z option but this option only works from the Start Programs (1.1) or Group (1.2) menus, not from the command line. (A process always inherits its initial maximum file handle count from its parent; from there, a process can only raise its own limit, never lower it.) The Microsoft OS/2 linker fails under the C shell even though it works fine under cmd.exe. Microsoft has determined there was a bug in the version of the C library used to build the link.exe distributed with MS C 5.1. The linker can fail if it's run as a child of a process that has a maximum file handle count greater than 20; this is a problem because the C shell sets its maximum to 255. If you're encountering this problem, try patching your link.exe file with the patchlnk.exe utility. (Type ``patchlnk - h'' for help.) When I try to run Microsoft's make.exe in the background it hangs. This is a known problem under OS/2 with make and certain other applications that need to spawn child processes of their own. The OS/2 process initialization and completion logic requests a semaphore in KBDCALLS.DLL that's already owned by whatever process in that window is already sleeping in a KbdCharIn call. Until another keystroke is pressed, that semaphore is never released and the background processes are never allowed to cleanly exit. This problem has been fixed in OS/2 2.0 and Page 21 Common Problems through CSD 5050 for OS/2 1.3 with a new KBDCALLS.DLL. That DLL for 1.3 is available on request from Hamilton Laboratories and can be downloaded from the listings area in the ``hamilton'' conference on BIX. copy or rename *.* doesn't work right. copy, xcopy, rename and del like to do their own wildcard expansion. To make them work sensibly, be sure your startup.csh file includes and that you use the aliases and procedure definitions we supply to intercept these commands to turn off shell wildcarding just long enough to run them. These definitions can also serve as a model if you discover other applications that must do their own wildcarding. For more information, refer to the discussion on page 85. The -! option doesn't work. The exclamation point is a special character for the shell. The shell lets you pick up text out of previous commands using history references that begin with ``!'' followed by a string that tells what text you're retrieving. To avoid having an exclamation confused as a history reference, be sure the exclamation is at the end of a word, so the next character is a space or a tab. grep '^foo' doesn't work. The circumflex has special meaning as the escape character to the C shell, even inside quotes. If you want to pass a literal ``^'' to grep (or anything else) from the command line, you must type ``^^'' unless the immediately preceding character was ``[''. When I list a directory over the network, not everything shows up. This is a known bug in the OS/2 networking code, not the C shell. The problem occurs if (1) the directory is read over a network, (2) directory entries are being read in blocks (for higher performance) rather than one-at-a- time and (3) the total number of characters in all the filenames in that directory happens to be just right. In all cases observed, adding or deleting any arbitrary entry in the directory makes the problem go away. The Page 22 Common Problems bug affects the C shell and its utilities because they use blocked reads; simpler programs like cmd.exe's DIR are unaffected because they read one entry at a time. The bug appears to have been introduced in IBM OS/2 EE CSD WR04098 and Microsoft Lan Manager 2.0, both issued around year-end, 1990. IBM has verified the problem and has developed a fix, which is now shipping as part of OS/2 EE 1.3. If you encounter the problem and you're an IBM customer, you should call 1-800-237-5511 or contact your local IBM representative and ask for a copy of the new netwksta.sys file being distributed as APAR IC02287. You can also download this file from the listings area of the ``hamilton'' vendor support conference on Bix or contact us directly and we'll mail you a copy. In the meantime, this release contains a work-around for disabling the block read feature. If you create an environmental variable, NETWORKBUG, and set it equal to 1, directory reads will be done only one-at-a-time, ensuring correct results at all times, albeit with some degradation in performance. You can do this either from the C shell: setenv NETWORKBUG = 1 or in your config.sys: SET NETWORKBUG=1 du, pwd and vol waste time sitting and spinning when they hit a removable drive that's empty. If you have a removable media device other than A: or B:, these utilities will normally try to report them. That's probably not you want, at least not usually; you can specify just the set of drives you do want reported using the DRIVEMASK environmental variable. Page 23 Common Problems cd /foo doesn't work. Hamilton C shell tries to serve users coming both UNIX and MS-Dos backgrounds. To do this, the C shell and all the utilities accept command line options to start with either ``-'' (UNIX-style) or ``/'' (Dos-style). It also recognizes filenames typed with either forward or backward slashes. But when you type ``cd /foo'', it guesses wrong and thinks you're trying to give it a command line option that it can't recognize. If this is really not what you intend, set the SWITCHCHARS environmental variable to just the specific characters you want recognized. E.g., you might include this in your config.sys to have only ``-'' recognized: set SWITCHCHARS=- I've just installed OS/2 1.2 and suddenly my environment variables don't work. The auto install program distributed with the fall, 1989 releases of OS/2 1.2 from Microsoft and IBM has a bug. It tries to automatically convert entries on the 1.1 Start Programs menu into corresponding entries on the new 1.2 Group Main menu. If the parameters line for starting a program has text on it (as the C shell's does), the entry is garbled even though it looks correct and causes a garbled environment to be passed to the shell. Editing the entry does not fix the problem. The only solution is to delete the entry and rekey it from scratch. I can't set my own screen colors. Yes, you can (finally, in this latest release.) But you cannot do it just by embedding ANSI escape sequences into your prompt since the C shell will immediately reset the colors back to what it thinks they should be. To set your own preferences for screen colors, you must use the COLORS environmental variable. See the chapter on customizing the shell or the colors.csh script in the samples directory for more information. The C shell's icon won't display in Group-Main. If you install the C shell as the default command processor by specifying it on the PROTSHELL line in Page 24 Common Problems config.sys and entering its path as ``*'' in Group-Main, you will see only the default OS/2 icon in Group-Main if you select View Icon. If you start, then minimize the C shell, it will have the correct icon, however. This has been reported to IBM. Their response is that, by design, when the path is an ``*,'' the Group code does not attempt to resolve the actual pathname (and whether there's any icon associated with it) until you actually click on the entry to start it. They agree this means you will not see the correct icon in the Group menu but claim this is what they intended and that it's not a bug. more crashes on the OS/2 2.0 Beta and LA Releases. The dynamic link library supporting 8514 displays in the beta and LA releases from IBM has a bug which causes some VIO applications, including more, to crash with a protection violation if they're run in a text window. They work fine full-screen. This problem has been fixed in the GA build. more hangs or exits prematurely on the OS/2 2.0 6.167 and LA releases. Under the 6.167 and LA releases, the 8514 display driver is completely unusable. It even has problems repainting the screen after a menu has been closed or displaying icons in the templates folder. It even causes more to hang the whole system if you have an 8514. But even using the VGA driver, random problems will be observed due, apparently, to bugs in the keyboard driver. Depending on what's fed to it through a pipe, more will occasionally prematurely exit after the first screenful. All these problems have been fixed in the GA release. The C shell can't change its title bar or icon under the OS/2 2.0 6.167 Beta and LA releases. This functionality was disabled in the 6.167 Beta and LA releases as part of the work to add the Workplace Shell. This problem has been fixed in the GA release. Alt-Enter doesn't work to grab commands from the history list under the OS/2 2.0 6.167 Beta Release. Page 25 Common Problems Under 6.167, Alt-Enter is gobbled up by the Workplace Shell as a keystroke combination used to signal that a VDM application should be toggled back and forth between the desktop and a full-screen session. If you type it anywhere else, it does nothing; it's not passed to the application. This has been fixed in the LA and GA releases. Under the 6.167 build, you'll have to type Ctrl-Shift-Enter instead. The C shell (and lots of other applications) only have default icons under the OS/2 2.0 6.167 Beta and LA Releases. The Workplace Shell does not support .ico files. All icons for text applications must be stored in the extended attributes. The latest builds of the C shell have the icon both in the EA and in an .ico file but if you copied the C shell onto your disk with a utility (e.g.., something other than cp) that does not support EA's, that information probably got lost. To put an icon into the extended attributes, use the OS/2 1.3 File Manager, selecting the file, pulling down ``Properties'' and selecting ``Icon...''. I just installed the C shell as the PROTSHELL and now when I start Commmunications Manager, it dies immediately. Communications Manager is invoked via a .cmd script file. Follow the instructions in step 4 on page 10 to rewrite that entry to start that script explicitly via cmd.exe. I can't wildcard filenames with $, quoted or escaped characters in them. Yes, you can (finally, in this latest release.) To do so, just quote or escape the special characters. E.g., to get all the files that begin with $, you might type ^$* or '$'* . I can't run the C shell inside an Epsilon editor window. The Epsilon editor tries to run whatever command processor you use by creating a full-screen session and Page 26 Common Problems doing a KbdRegister to intercept the KbdStringIn API entry so that Epsilon can feed it whatever you type in the editor window. Output (stdout and stderr) from the child session is redirected over a pipe back to the editor. There are a couple problems in their approach: (1) They neglected to consider that not all applications use KbdStringIn; if stdin is attached to a keyboard, the C shell reads a keystroke at a time using KbdCharIn and those calls still end up tied to that full-screen session rather than being redirected. (If stdin is attached to anything else, it uses DosRead calls.) The authors of Epsilon really should have intercepted the whole set of Kbd calls, not just one of them. (2) Not all applications write their output to stdout or stderr; applications like more, that use Vio output, won't run properly. Their output appears in that full-screen session, not back in the editor window. Epsilon really should be doing a VioRegister to grab the Vio output also. We are working with Lugaru Software (the authors of Epsilon) on a solution that should be available shortly. A partial workaround is to tell Epsilon to use a separate program, which just reads input and pipes it to the C shell. Marty Klos at IBM has written a small C program to do that and placed it in the public domain. A copy is available on request from us or may be downloaded from the listings area of the ``hamilton'' vendor support conference on BIX. rm doesn't remove anything, it just puts everything in a hidden directory. You're using the notorious Microsoft rm command instead of the Hamilton rm. The Microsoft rm doesn't remove anything; it just puts things in a hidden system directory. Hamilton rm is actually in hrm.exe under Windows NT and should be aliased to rm in your startup.csh file. Fix that and then, to get rid of all those ``deleted'' directories: cd \; rm -x `ls -1ra +H | dim | grep 'deleted$'` Page 27 Common Problems Page 28 Product Support If you encounter problems or would like to make suggestions for a future revision, please contact us by any of the following or by regular mail; we promise a prompt response. Phone: 508-358-5715 FAX: 508-358-1113 MCI Mail: 389-0321 Telex: 6503890321 BIX: hamilton CompuServe: 70034,2025 Internet: 3890321@mcimail.com Also, on Bix, we have a vendor support conference. Do a ``join hamilton'' once you get on or follow the menus into the conference system. Bug Reports If you encounter what you believe to be a bug, please try to experiment to see what specific command or command sequence seems to be failing before calling. A problem that's easily reproducible is obviously easier to fix. Built in to Hamilton C shell are a number of consistency checks to trap bugs before they cause damage and to snapshot enough information to help us diagnose and repair the problem. If the shell is actually crashing, look to see if a new entry has been added to the error log, crash.csh, in your home directory; that information will be useful. When you call, we'll try to provide an immediate workaround if there is one. If the problem is serious but straight-forwardly correctable, we can generally offer an interim release at no charge to fix that specific problem. At the very least, we try to schedule it for an upcoming general release. Future Enhancements Work continues on additional features and enhancements. As they become available, we want you to have them. Page 29 Support Please return the registration form by mail or FAX. Without that, we often have no way of knowing who you are to send updates to. This is particularly true if your copy was purchased through your company's purchasing department or through a retail distributor. Also, we look forward to your feedback as we strive to improve the product. Page 30 Page 31 User Guide User Guide Getting Started Starting Hamilton C shell is simple: select it from the Start Programs window or the Program Selector or type ``csh'' as a command to cmd.exe. After the initial greeting, you'll see the first prompt: (The underscore is meant to be the cursor.) Hamilton C shell(tm) Release 2.1 Copyright (c) 1988-1993 by Hamilton Laboratories. All rights reserved. 1 D% _ This tells you that it will remember what you type as command number 1 and that your current drive is D. The ``%'' is traditional; rather like the ``>'' for DOS. Naturally, you can change your prompt if you want, to be anything you like. For example, to get a prompt that looks like one you might get from cmd.exe+: 1 D% set prompt1 = '[$upper(cwd)] ' [D:\DOUG] _ This works by taking the value of the cwd (current working directory) variable, turning it to upper case using one of the built-in procedures and pasting left and right brackets around it. The value is recalculated each time a prompt is given, so it always displays an up-to- date value. (Lists of all the built-in variables and procedures are given in later sections.) To set it back: [D:\DOUG] set prompt1 = '$@ $CDISK% ' 3 D% _ ____________________ + We introduce this is as the first example with some trepidation: the prompt seems to be the first thing people want to change. But it can also be one of the more daunting projects if you're getting started. This example is offered more in the spirit of assurance that, with a little experience, the prompt can be set to anything you like. Page 32 User Guide Basic Statements Generally speaking, whatever commands you might have typed into cmd.exe will still work here. Even an ``internal'' cmd.exe function like dir works: 3 D% dir The volume label in drive D is USER. Directory of D:\DOUG\SH\DOCS\SCRIPT\HELLO .